﻿<html DIR="LTR" xmlns:tool="http://www.microsoft.com/tooltip" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
  <head>
    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=utf-8" />
    <META NAME="save" CONTENT="history" />
    <title>Tracing Driver Operation</title>
    
    <link rel="stylesheet" type="text/css" href="../local/Classic.css">
      
    </link>
    
    <script src="../local/script.js">
      
    </script><script src="../local/script_main.js">&amp;nbsp;</script>
  </head>
  <body>
    <!--Topic built:09/24/2007 09:01:38-->

    
    
    
    
    
    
    
    
    
    <div id="header">
      <table width="100%" id="topTable"><tr>
          <td align="left">
            <span id="headerBold">Tracing Driver Operation</span>
          </td>
          <td align="right">
            
          </td>
        </tr></table>
      
      
      
    </div>
    <div id="mainSection">
      
        
        
		<font color="DarkGray"><!-- [This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]<br/>[Documentation built on $$TIMESTAMP$$]  --> </font> <p /> <p />
	
        <div id="introductionSection" class="section">
    <p>The Microsoft SQL Server 2005 JDBC Driver supports the use of tracing (or logging) to help resolve issues and problems with the JDBC driver when it is used in your application. To enable the use of tracing, the JDBC driver uses the logging APIs in java.util.logging, which provides a set of classes for creating <b>Logger</b> and <b>LogRecord</b> objects. </p>
    <div style="margin: .5em 1.5em .5em 1.5em"><b>Note: </b>
      For the native component (sqljdbc_xa.dll) that is included with the JDBC driver, tracing is enabled by the Built-In Diagnostics (BID) framework. For information about BID, see <a href="http://go.microsoft.com/fwlink/?LinkId=70042" target="_blank" alt=""><linkText xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">Data Access Tracing in SQL Server 2005</linkText></a>. <p />
    </div>
    <p>When you develop your application, you can make calls to <b>Logger</b> objects, which in turn create <b>LogRecord</b> objects, which are then passed to <b>Handler</b> objects for processing. <b>Logger</b> and <b>Handler</b> objects both use logging levels, and optionally logging filters, to regulate which <b>LogRecords</b> are processed. When the logging operations are complete, the <b>Handler</b> objects can optionally use <b>Formatter</b> objects to publish the log information.</p>
    <p>By default, the java.util.logging framework writes its output to a file. This output log file must have write permissions for the context under which the JDBC driver is running.</p>
    <div style="margin: .5em 1.5em .5em 1.5em"><b>Note: </b>
      For more information about using the various logging objects for program tracing, see the <a href="http://go.microsoft.com/fwlink/?LinkId=57239" target="_blank" alt=""><linkText xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">Java Logging APIs</linkText></a> documentation on the Sun Microsystems Web site.<p />
    </div>
    <p>The following sections describe the logging levels and the categories that can be logged, and provide information about how to enable tracing in your application.</p>
  </div><h1 class="heading">Logging Levels</h1><div id="sectionSection0" class="section"><content xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
      <p xmlns="">Every log message that is created has an associated logging level. The logging level determines the importance of the log message, which is defined by the <b>Level</b> class in java.util.logging. The following table describes each of the available logging levels.</p>
      <table width="100%" cellspacing="0" cellpadding="0" border="1" style="background-color: #CCCCCC;" xmlns=""><tr>
            <th>
              Name
            </th>
            <th>
              Description
            </th>
          </tr><tr>
          <td>
            <p>SEVERE</p>
          </td>
          <td>
            <p>Indicates a serious failure and is the highest level of logging. In the JDBC driver, this level is used for reporting errors and exceptions.</p>
          </td>
        </tr><tr>
          <td>
            <p>WARNING</p>
          </td>
          <td>
            <p>Indicates a potential problem.</p>
          </td>
        </tr><tr>
          <td>
            <p>INFO</p>
          </td>
          <td>
            <p>Provides informational messages.</p>
          </td>
        </tr><tr>
          <td>
            <p>CONFIG</p>
          </td>
          <td>
            <p>Provides configuration messages. In the JDBC driver, this level is used for configuration settings that are global in scope.</p>
          </td>
        </tr><tr>
          <td>
            <p>FINE</p>
          </td>
          <td>
            <p>Provides tracing information. In the JDBC driver, this level is used for most log messages.</p>
          </td>
        </tr><tr>
          <td>
            <p>FINER</p>
          </td>
          <td>
            <p>Provides detailed tracing information.</p>
          </td>
        </tr><tr>
          <td>
            <p>FINEST</p>
          </td>
          <td>
            <p>Provides highly detailed tracing information. This is the lowest level of logging.</p>
          </td>
        </tr><tr>
          <td>
            <p>OFF</p>
          </td>
          <td>
            <p>Turns off logging.</p>
          </td>
        </tr><tr>
          <td>
            <p>ALL</p>
          </td>
          <td>
            <p>Enables logging of all messages.</p>
          </td>
        </tr></table>
    </content></div><h1 class="heading">Logging Categories</h1><div id="sectionSection1" class="section"><content xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
      <p xmlns="">When you create a <b>Logger</b> object, you must tell the object which named entity or category that you are interested in getting log information from. The JDBC driver supports the following logging categories.</p>
      <table width="100%" cellspacing="0" cellpadding="0" border="1" style="background-color: #CCCCCC;" xmlns=""><tr>
            <th>
              Name
            </th>
            <th>
              Description
            </th>
          </tr><tr>
          <td>
            <p>SQLServerConnection</p>
          </td>
          <td>
            <p>Logs messages in the <a href="937292a6-1525-423e-a2b2-a18fd34c2893.htm">SQLServerConnection</a> class. The default logging level is FINE.</p>
          </td>
        </tr><tr>
          <td>
            <p>SQLServerStatement</p>
          </td>
          <td>
            <p>Logs messages in the <a href="ec24963c-8b51-4838-91e9-1fbfa2347451.htm">SQLServerStatement</a> class. The default logging level is FINE.</p>
          </td>
        </tr><tr>
          <td>
            <p>TDS.DATA</p>
          </td>
          <td>
            <p>Logs TDS messages. This category creates very verbose and detailed messages, and can only be enabled by setting the logging level to FINEST.</p>
          </td>
        </tr><tr>
          <td>
            <p>TDS.TOKEN</p>
          </td>
          <td>
            <p>Logs TDS messages. This category logs only the tokens within the TDS packets, and is less verbose than the TDS.DATA category.</p>
          </td>
        </tr><tr>
          <td>
            <p>XA</p>
          </td>
          <td>
            <p>Logs messages for all XA transactions in the <a href="5ecb4bf1-b8d1-47cf-9cb1-7a18acc11ce2.htm">SQLServerXAConnection</a>, <a href="df957b79-536f-4db7-b6ac-3d59343559fc.htm">SQLServerXAResource</a>, and <a href="95fc7b07-2498-4a7e-8f7f-ee0d86b598b4.htm">SQLServerXADataSource</a> classes. The default logging level is FINE.</p>
          </td>
        </tr><tr>
          <td>
            <p>SQLServerDataSource</p>
          </td>
          <td>
            <p>Logs messages in the <a href="097434fd-2b74-411c-a5ed-eba04481dde5.htm">SQLServerDataSource</a>, <a href="b00e5a90-2af7-4d04-8ef8-256183777dcf.htm">SQLServerConnectionPoolDataSource</a>, and <a href="4c87e9d3-904a-4b86-90cc-3684034c86ee.htm">SQLServerPooledConnection</a> classes. The default logging level is FINE. </p>
          </td>
        </tr></table>
    </content></div><h1 class="heading">Enabling Tracing Programmatically</h1><div id="sectionSection2" class="section"><content xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
      <p xmlns="">Tracing can be enabled programmatically by creating a <b>Logger</b> object and indicating the category to be logged. For example, the following code shows how to enable logging for SQL statements:</p>
      <div class="sampleCode" xmlns=""><span codeLanguage="other"><pre>Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.SQLServerStatement");
logger.setLevel(Level.FINE);</pre></span></div>
      <p xmlns="">To turn off logging in your code, use the following:</p>
      <div class="sampleCode" xmlns=""><span codeLanguage="other"><pre>logger.setLevel(Level.OFF);</pre></span></div>
      <p xmlns="">To log all available categories, use the following:</p>
      <div class="sampleCode" xmlns=""><span codeLanguage="other"><pre>Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc");
logger.setLevel(Level.FINE);</pre></span></div>
      <p xmlns="">To disable a specific category from being logged, use the following:</p>
      <div class="sampleCode" xmlns=""><span codeLanguage="other"><pre>Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.TDS");
logger.setLevel(Level.OFF);</pre></span></div>
    </content></div><h1 class="heading">Enabling Tracing by Using the Logging.Properties File</h1><div id="sectionSection3" class="section"><content xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
      <p xmlns="">You can also enable tracing by using the<code> logging.properties </code>file, which can be found in the<code> lib </code>directory of your Java Runtime Environment (JRE) installation. This file can be used to set the default values for the loggers and handlers that will be used when tracing is enabled.</p>
      <p xmlns="">The following is an example of the settings that you can make in the <code>logging.properties</code> files:</p>
      <div class="sampleCode" xmlns=""><span codeLanguage="other"><pre>   # Specify the handlers to create in the root logger
   # (all loggers are children of the root logger).
   # The following creates two handlers.
   handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler

   # Set the default logging level for the root logger.
   .level = OFF

   # Set the default logging level for new ConsoleHandler instances.
   java.util.logging.ConsoleHandler.level = FINE

   # Set the default logging level for new FileHandler instances.
   java.util.logging.FileHandler.level = OFF

   # Set the default formatter for new ConsoleHandler instances.
   java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

   # Set the default logging level for the logger named ConnectionPool.
   ConnectionPool.level = OFF</pre></span></div>
      <div style="margin: .5em 1.5em .5em 1.5em" xmlns=""><b>Note: </b>
        You can set the properties in the<code> logging.properties </code>file by using the <b>LogManager</b> object that is part of java.util.logging.<p />
      </div>
    </content></div><span id="seeAlsoSpan"><h1 class="heading">See Also</h1></span><div id="seeAlsoSection" class="section" name="collapseableSection"><a href="723e2680-a0c5-4a7d-a319-1e49e41078cf.htm">Diagnosing Problems with the JDBC Driver</a><br /><br /></div><!--[if gte IE 5]>
			<tool:tip element="seeAlsoToolTip" avoidmouse="false"/><tool:tip element="languageFilterToolTip" avoidmouse="false"/><tool:tip element="roleInfoSpan" avoidmouse="false"/>
		<![endif]-->
      <div id="footer" class="section">
        
		<hr />
		
		<span id="fb" class="feedbackcss">
			
			
		</span>
		
		<a href="9bad553b-9e70-4696-8499-2e35f772a1e0.htm">
			
			© 2007 Microsoft Corporation. All rights reserved.
		</a>
 	
	
      </div>
    </div>
  </body>
</html>